<!DOCTYPE html
  PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-us" xml:lang="en-us">
<head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<meta name="copyright" content="(C) Copyright 2005">
<meta name="DC.rights.owner" content="(C) Copyright 2005">
<meta name="DC.Type" content="topic">
<meta name="DC.Title" content="Specializing domains in DITA">
<meta name="abstract" content="In current approaches, DTDs are static. As a result, DTD designers try to cover every contingency and, when this effort fails, users have to force their information to fit existing types. DITA changes this situation by giving information architects and developers the power to extend a base DTD to cover their domains.">
<meta name="description" content="In current approaches, DTDs are static. As a result, DTD designers try to cover every contingency and, when this effort fails, users have to force their information to fit existing types. DITA changes this situation by giving information architects and developers the power to extend a base DTD to cover their domains.">
<meta name="DC.Relation" scheme="URI" content="DITA-rm.html">
<meta name="DC.Relation" scheme="URI" content="DITA-dsf.html">
<meta name="DC.Relation" scheme="URI" content="DITA-mapdomains.html">
<meta name="DC.Creator" content="Erik Hennum; IBM Corporation; ehennum@us.ibm.com. Erik Hennum works on the design and implementation of User Assistance for the IBM Storage Systems Group.">
<meta name="DC.Format" content="XHTML">
<meta name="DC.Identifier" content="domains">
<meta name="DC.Language" content="en-us">
<link rel="stylesheet" type="text/css" href="commonltr.css">
<title>Specializing domains in DITA</title>
</head>
<body id="domains"><a name="domains"><!-- --></a>


  <h1 class="topictitle1">Specializing domains in DITA</h1>

  
  
  <div><p>In current approaches, DTDs are static. As a result, DTD designers try to cover every contingency and, when this effort fails, users have to force their information to fit existing types. DITA changes this situation by giving information architects and developers the power to extend a base DTD to cover their domains.</p>

    <p>The Darwin Information Typing Architecture (DITA) is an XML architecture for extensible technical information. A domain extends DITA with a set of elements whose names and content models are unique to an organization or field of knowledge. Architects and authors can combine elements from any number of domains, leading to great flexibility and precision in capturing the semantics and structure of their information. In this overview, you learn how to define your own domains.</p>

  </div>
  <div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="DITA-rm.html" title="This document is a roadmap for the Darwin Information Typing Architecture: what it is and how it applies to technical documentation. It is also a product of the architecture, having been written entirely in XML and produced using the principles described here...">Introduction to the Darwin Information Typing Architecture</a></div>
<div class="previouslink"><strong>Previous topic:</strong> <a href="DITA-dsf.html" title="The Darwin Information Typing Architecture (DITA) provides a way for documentation authors and architects to create collections of typed topics that can be easily assembled into various delivery contexts. Topic specialization is the process by which authors and architects can define topic types, while maintaining compatibility with existing style sheets, transforms, and processes. The new topic types are defined as an extension, or delta, relative to an existing topic type, thereby reducing the work necessary to define and maintain the new type.">Specializing topic types in DITA</a></div>
<div class="nextlink"><strong>Next topic:</strong> <a href="DITA-mapdomains.html" title="The benefits of formal information typing are well known for the content of topics, but collections of topics also benefit from formal organizing structure. Such formal structures guide authors while they assemble collections of topics and ensure consistent large-scale patterns of information for the user. Using DITA map domains, a designer can define a formal information architecture that can be reused in many deliverables.">How to define a formal information architecture with DITA map domains</a></div>
</div>
</div>
<div class="nested1" id="intro"><a name="intro"><!-- --></a>
    <h2 class="topictitle2">Introducing domain specialization</h2>

    <div>
      <p>In DITA, the topic is the basic unit of processable content. The topic provides the title, metadata, and structure for the content. Some topic types provide very simple content structures. For example, the <span class="apiname">concept</span> topic has a single concept body for all of the concept content. By contrast, a <span class="apiname">task</span> topic articulates a structure that distinguishes pieces of the task content, such as the prerequisites, steps, and results.</p>

      <p>In most cases, these topic structures contain content elements that are not specific to the topic type. For example, both the concept body and the task prerequisites permit common block elements such as <span class="apiname">p</span> paragraphs and <span class="apiname">ul</span> unordered lists.</p>

      <p><dfn class="term">Domain specialization</dfn> lets you define new types of content elements independently of topic type. That is, you can derive new phrase or block elements from the existing phrase and block elements. You can use a specialized content element within any topic structure where its base element is allowed. For instance, because a <span class="apiname">p</span> paragraph can appear within a concept body or task prerequisite, a specialized paragraph could appear there, too.</p>

      <div class="fignone">
        <img src="image/content_special.gif" height="125" width="406" alt="specialized content can be inserted in topic bodies">
        <p>Here's an analogy from the kitchen. You might think of topics as types of containers for preparing food in different ways, such as a basic frying pan, blender, and baking dish. The content elements are like the ingredients that go into these containers, such as spices, flour, and eggs. The domain resembles a specialty grocer who provides ingredients for a particular cuisine. Your pot might contain chorizo from the carnicería when you're cooking TexMex or risotto when you're cooking Italian. Similarly, your topics can contain elements from the programming domain when you're writing about a programming language or elements from the UI domain when you're writing about a GUI application.</p>

        <p>DITA has broad tastes, so you can mix domains as needed. If you're describing how to program GUI applications, your topics can draw on elements from both the programming and UI domains. You can also create new domains for <em>your</em> content. For instance, a new domain could provide elements for describing hardware devices. You can also reuse new domains created by others, expanding the variety of what you can cook up.</p>

        <p>In a more formal definition, topic specialization starts with the containing element and works from the top down. Domain specialization, on the other hand, starts with the contained element and works from the bottom up.</p>

      </div>

    </div>

  </div>

  <div class="nested1" id="base"><a name="base"><!-- --></a>
    <h2 class="topictitle2">Understanding the base domains</h2>

    <div>
      <p>A DITA <dfn class="term">domain</dfn> collects a set of specialized content elements for some purpose. In effect, a domain provides a specialized vocabulary. With the base DITA package, you receive the following domains:</p>

      
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
          <thead align="left">
            <tr>
              <th class="cellrowborder" valign="top" id="d21e121">Domain</th>

              <th class="cellrowborder" valign="top" id="d21e124">Purpose</th>

            </tr>

          </thead>

          <tbody>
            <tr>
              <td class="cellrowborder" valign="top" headers="d21e121 d21e124 ">highlight</td>

              <td class="cellrowborder" valign="top" headers="d21e121 d21e124 ">To highlight text with styles such as bold, italic, and monospace</td>

            </tr>

            <tr>
              <td class="cellrowborder" valign="top" headers="d21e121 d21e124 ">programming</td>

              <td class="cellrowborder" valign="top" headers="d21e121 d21e124 ">To define the syntax and give examples of programming languages</td>

            </tr>

            <tr>
              <td class="cellrowborder" valign="top" headers="d21e121 d21e124 ">software</td>

              <td class="cellrowborder" valign="top" headers="d21e121 d21e124 ">To describe the operation of a software program</td>

            </tr>

            <tr>
              <td class="cellrowborder" valign="top" headers="d21e121 d21e124 ">UI</td>

              <td class="cellrowborder" valign="top" headers="d21e121 d21e124 ">To describe the user interface of a software program</td>

            </tr>

          </tbody>

        </table>
</div>

      <p>In most domains, a specialized element adds semantics to the base element. For example, the <span class="apiname">apiname</span> element of the programming domain extends the basic <span class="apiname">keyword</span> element with the semantic of a name within an API.</p>

      <p>The highlight domain is a special case. The elements in this domain provide styled presentation instead of semantic or structural markup. The highlight styles give authors a practical way to mark up phrases for which a semantic has not been defined. </p>

      <p>Providing such highlight styles through a domain resolves a long-standing dispute for publication DTDs. Purists can omit the highlight domain to enforce documents that should be strictly semantic. Pragmatists can include the highlight domain to provide expressive flexibility for real-world authoring. A semipragmatist could even include the highlight domain in conceptual documents to support expressive authoring but omit the highlight domain from reference documents to enforce strict semantic tagging. </p>

      <p>More generally, you can define documents with any combination of domains and topics. As we'll see in <a href="#generalize">Generalizing a domain</a>, the resulting documents can still be exchanged.</p>

    </div>

  </div>

  <div class="nested1" id="combine"><a name="combine"><!-- --></a>
    <h2 class="topictitle2">Combining an existing topic and domain</h2>

    <div>
      <p>The DITA package provides a DTD for each topic type and an omnibus DTD (<span class="filepath">ditabase.dtd</span>) that defines all of the topic types. Each of these DTDs includes all of the predefined DITA domains. Thus, topics written against one of the supplied DTDs can use all of the predefined domain specializations.</p>

      <p>Behind the scenes, a DITA DTD is just a shell. Elements are actually defined in other modules, which are included in the DTD. Through these modules, DITA provides you with the building blocks to create new combinations of topic types and domains.</p>

      <p>When you add a domain to your DITA installation, the new domain provides you with additional modules. You can use the additional modules to incorporate the domain into the existing DTDs or to create new DTDs.</p>

      <p>In particular, each domain is implemented with two files:</p>

      <ul>
        <li>
          <p>A file that declares the entities for the domain. This file has the <span class="filepath">.ent</span> extension.</p>

        </li>

        <li>
          <p>A file that declares the elements for the domain. This file has the <span class="filepath">.mod</span> extension.</p>

        </li>

      </ul>

      <p>As an example, let's say we're authoring the reference topics for a programming language. We're purists about presentation, so we want to exclude the highlight domain. We also have no need for the software or UI domains in this reference. We could address this scenario by defining a new shell DTD that combines the reference topic with the programming domain, excluding the other domains. </p>

      <p>A shell DTD has a consistent design pattern with a few well-defined sections. The instructions in these sections perform the following actions:</p>

      <ol>
        <li>
          <p>Declare the entities for the domains.</p>

          <p>In the scenario, this section would include the programming domain entities:</p>

          <pre class="codeblock">&lt;!ENTITY % pr-d-dec PUBLIC "-//IBM//ENTITIES DITA Programming Domain//EN" "programming-domain.ent"&gt;
  %pr-d-dec;
</pre>

        </li>

        <li>
          <p>Redefine the entities for the base content elements to add the specialized content elements from the domains.</p>

          <p>This section is crucial for domain specialization. Here, the design pattern makes use of two kinds of entities. Each base content element has an <dfn class="term">element entity</dfn> to identify itself and its specializations. Each domain provides a separate <dfn class="term">domain specialization entity</dfn> to list the specializations that it provides for a base element. By combining the two kinds of entities, the shell DTD allows the specialized content elements to be used in the same contexts as the base element.</p>

          <p>In the scenario, the <span class="apiname">pre</span> element entity identifies the <span class="apiname">pre</span> element (which, as in HTML, contains preformatted text) and its specializations. The programming domain provides the <span class="apiname">pr-d-pre</span> domain specialization entity to list the specializations for the <span class="apiname">pre</span> base element. The same pattern is used for the other base elements specialized by the programming domain:</p>

          <pre class="codeblock">&lt;!ENTITY % pre     "pre     | %pr-d-pre;"&gt;
&lt;!ENTITY % keyword "keyword | %pr-d-keyword;"&gt;
&lt;!ENTITY % ph      "ph      | %pr-d-ph;"&gt;
&lt;!ENTITY % fig     "fig     | %pr-d-fig;"&gt;
&lt;!ENTITY % dl      "dl      | %pr-d-dl;"&gt;
</pre>

          <p>To learn which content elements are specialized by a domain, you can look at the entity declaration file for the domain.</p>

        </li>

        <li>
          <p>Define the <span class="apiname">domains</span> attribute of the topic elements to declare the domains represented in the document.</p>

          <p>Like the <span class="apiname">class</span> attribute, the <span class="apiname">domains</span> attribute identifies dependencies. Where the <span class="apiname">class</span> attribute identifies base elements, the <span class="apiname">domains</span> attribute identifies the domains available within a topic. Each domain provides a <dfn class="term">domain identification entity</dfn> to identify itself in the <span class="apiname">domains</span> attribute.</p>

          <p>In the scenario, the only topic is the <span class="apiname">reference</span> topic. The only domain is the programming domain, which is identified by the <samp class="codeph">pr-d-att</samp> domain identification entity:</p>

          <pre class="codeblock">&lt;!ATTLIST reference  domains CDATA "&amp;pr-d-att;"&gt;
</pre>

        </li>

        <li>
          <p>Redefine the infotypes entity to specify the topic types that can be nested within a topic.</p>

          <p>In the scenario, this section would declare the <span class="apiname">reference</span> topic:</p>

          <pre class="codeblock">&lt;!ENTITY % info-types "reference"&gt;
</pre>

        </li>

        <li>
          <p>Define the elements for the topic type, including the base topics.</p>

          <p>In the scenario, this section would include the base topic and reference topic modules:</p>

          <pre class="codeblock">&lt;!ENTITY % topic-type PUBLIC "-//IBM//ELEMENTS DITA Topic//EN" "topic.mod"&gt;
  %topic-type;
&lt;!ENTITY % reference-typemod PUBLIC "-//IBM//ELEMENTS DITA Reference//EN" "reference.mod"&gt;
  %reference-typemod;
</pre>

        </li>

        <li>
          <p>Define the elements for the domains.</p>

          <p>In the scenario, this section would include the programming domain definition module:</p>

          <pre class="codeblock">&lt;!ENTITY % pr-d-def PUBLIC "-//IBM//ELEMENTS DITA Programming Domain//EN" "programming-domain.mod"&gt;
  %pr-d-def;
</pre>

        </li>

      </ol>

      <p>Often, it would be easiest to work by copying an existing DTD and adding or removing topics or domains. In the scenario, it would be easiest to start with <span class="filepath">reference.dtd</span> and remove the highlight, software, and UI domains as shown with the underlined text below.</p>

      <pre class="codeblock">&lt;!--vocabulary declarations--&gt;
<u>&lt;!ENTITY % ui-d-dec PUBLIC "-//IBM//ENTITIES DITA User Interface Domain//EN" "ui-domain.ent"&gt;
  %ui-d-dec;
&lt;!ENTITY % hi-d-dec PUBLIC "-//IBM//ENTITIES DITA Highlight Domain//EN" "highlight-domain.ent"&gt;
  %hi-d-dec;</u>
&lt;!ENTITY % pr-d-dec PUBLIC "-//IBM//ENTITIES DITA Programming Domain//EN" "programming-domain.ent"&gt;
  %pr-d-dec;
<u>&lt;!ENTITY % sw-d-dec PUBLIC "-//IBM//ENTITIES DITA Software Domain//EN" "software-domain.ent"&gt;
  %sw-d-dec;</u>

&lt;!--vocabulary substitution--&gt;
&lt;!ENTITY % pre     "pre     | %pr-d-pre;     <u>| %sw-d-pre;</u>"&gt;
&lt;!ENTITY % keyword "keyword | %pr-d-keyword; <u>| %sw-d-keyword; | %ui-d-keyword;</u>"&gt;
&lt;!ENTITY % ph      "ph      | %pr-d-ph;      <u>| %sw-d-ph;      | %hi-d-ph; | %ui-d-ph;</u>"&gt;
&lt;!ENTITY % fig     "fig     | %pr-d-fig;"&gt;
&lt;!ENTITY % dl      "dl      | %pr-d-dl;"&gt;

&lt;!--vocabulary attributes--&gt;
&lt;!ATTLIST reference  domains CDATA "<u>&amp;ui-d-att; &amp;hi-d-att;</u> &amp;pr-d-att; <u>&amp;sw-d-att;</u>"&gt;

&lt;!--Redefine the infotype entity to exclude other topic types--&gt;
&lt;!ENTITY % info-types "reference"&gt;

&lt;!--Embed topic to get generic elements --&gt;
&lt;!ENTITY % topic-type PUBLIC "-//IBM//ELEMENTS DITA Topic//EN" "topic.mod"&gt;
  %topic-type;

&lt;!--Embed reference to get specific elements --&gt;
&lt;!ENTITY % reference-typemod PUBLIC "-//IBM//ELEMENTS DITA Reference//EN" "reference.mod"&gt;
  %reference-typemod;

&lt;!--vocabulary definitions--&gt;
<u>&lt;!ENTITY % ui-d-def PUBLIC "-//IBM//ELEMENTS DITA User Interface Domain//EN" "ui-domain.mod"&gt;
  %ui-d-def;
&lt;!ENTITY % hi-d-def PUBLIC "-//IBM//ELEMENTS DITA Highlight Domain//EN" "highlight-domain.mod"&gt;
  %hi-d-def;</u>
&lt;!ENTITY % pr-d-def PUBLIC "-//IBM//ELEMENTS DITA Programming Domain//EN" "programming-domain.mod"&gt;
  %pr-d-def;
<u>&lt;!ENTITY % sw-d-def PUBLIC "-//IBM//ELEMENTS DITA Software Domain//EN" "software-domain.mod"&gt;
  %sw-d-def;</u>
</pre>

    </div>

  </div>

  <div class="nested1" id="new"><a name="new"><!-- --></a>
    <h2 class="topictitle2">Creating a domain specialization</h2>

    <div>
      <p>For some documents, you may need new types of content elements. In a common scenario, you need to mark up phrases that have special semantics. You can handle such requirements by creating new specializations of existing content elements and providing a domain to reuse the new content elements within topic structures.</p>

      <p>As an example, let's say we're writing the documentation for a class library. We intend to write processes that will index the documentation by class, field, and method. To support this processing, we need to mark up the names of classes, fields, and methods within the topic content, as in the following sample: </p>

      <pre class="codeblock">&lt;p&gt;The &lt;classname&gt;String&lt;/classname&gt; class provides
the &lt;fieldname&gt;length&lt;/fieldname&gt; field and 
the &lt;methodname&gt;concatenate()&lt;/methodname&gt; method.
&lt;/p&gt;</pre>

      <p>We must define new content elements for these names. Because the names are special types of names within an API, we can specialize the new elements from the <span class="apiname">apiname</span> element provided by the programming domain.</p>

      <p>The design pattern for a domain requires an abbreviation to represent the domain. A sensible abbreviation for the class library domain might be <samp class="codeph">cl</samp>. The identifier for a domain consists of the abbreviation followed by <samp class="codeph">-d</samp> (for domain).</p>

      <p>As noted in <a href="#combine">Combining an existing topic and domain</a>, the domain requires an entity declaration file and an element definition file.</p>

      <div class="section"><h3 class="sectiontitle">Writing the entity declaration file</h3>
        
        <p>The entity declaration file has sections that perform the following actions:</p>

        <ol>
          <li>
            <p>Define the domain specialization entities.</p>

            <p>A domain specialization entity lists the specialized elements provided by the domain for a base element. For clarity, the entity name is composed of the domain identifier and the base element name. The domain provides domain specialization entities for ancestor elements as well as base elements.</p>

            <p>In the scenario, the domain defines a domain specialization entity for the <span class="apiname">apiname</span> base element as well as the <span class="apiname">keyword</span> ancestor element (which is the base element for <span class="apiname">apiname</span>):</p>

            <pre class="codeblock">&lt;!ENTITY % cl-d-apiname "classname | fieldname | methodname"&gt;
&lt;!ENTITY % cl-d-keyword "classname | fieldname | methodname"&gt;
</pre>

          </li>

          <li>
            <p> Define the domain identification entity.</p>

            <p>The domain identification entity lists the topic type as well as the domain and other domains for which the current domain has dependencies. Each domain is identified by its domain identifier. The list is enclosed in parentheses. For clarity, the entity name is composed of the domain identifier and <samp class="codeph">-att</samp>.</p>

            <p>In the scenario, the class library domain has a dependency on the programming domain, which provides the <span class="apiname">apiname</span> element:</p>

            <pre class="codeblock">&lt;!ENTITY cl-d-att "(topic pr-d cl-d)"&gt;</pre>

          </li>

        </ol>

        <p>The complete entity declaration file would look as follows:</p>

        <pre class="codeblock">&lt;!ENTITY % cl-d-apiname "classname | fieldname | methodname"&gt;
&lt;!ENTITY % cl-d-keyword "classname | fieldname | methodname"&gt;

&lt;!ENTITY cl-d-att "(topic pr-d cl-d)"&gt;
</pre>

      </div>

      <div class="section"><h3 class="sectiontitle">Writing the element definition file</h3>
        
        <p>The element definition file has sections that perform the following actions:</p>

        <ol>
          <li>
            <p>Define the content element entities for the elements introduced by the domain.</p>

            <p>These entities permit other domains to specialize from the elements of the current domain.</p>

            <p>In the scenario, the class library domain follows this practice so that additional domains can be added in the future. The domain defines entities for the three new elements:</p>

            <pre class="codeblock">&lt;!ENTITY % classname  "classname"&gt;
&lt;!ENTITY % fieldname  "fieldname"&gt;
&lt;!ENTITY % methodname "methodname"&gt;
</pre>

          </li>

          <li>
            <p> Define the elements.</p>

            <p>The specialized content model must be consistent with the content model for the base element. That is, any possible contents of the specialized element must be generalizable to valid contents for the base element. Within that limitation, considerable variation is possible. Specialized elements can be substituted for elements in the base content model. Optional elements can be omitted or required. An element with multiple occurrences can be replaced with a list of specializations of that element, and so on.</p>

            <p>The specialized content model should always identify elements through the element entity rather than directly by name. This practice lets other domains merge their specializations into the current domain.</p>

            <p>In the scenario, the elements have simple character content:</p>

            <pre class="codeblock">&lt;!ELEMENT classname        (#PCDATA)&gt;
&lt;!ELEMENT fieldname        (#PCDATA)&gt;
&lt;!ELEMENT methodname       (#PCDATA)&gt;
</pre>

          </li>

          <li>
            <p>Define the specialization hierarchy for the element with <span class="apiname">class</span> attribute.</p>

            <p>For a domain element, the value of the attribute must start with a plus sign. Elements provided by domains should be qualified by the domain identifier.</p>

            <p>In the scenario, specialization hierarchies include the <span class="apiname">keyword</span> ancestor element provided by the base topic and the <span class="apiname">apiname</span> element provided by the programming domain:</p>

            <pre class="codeblock">&lt;!ATTLIST classname      class CDATA "+ topic/keyword pr-d/apiname cl-d/classname "&gt;
&lt;!ATTLIST fieldname      class CDATA "+ topic/keyword pr-d/apiname cl-d/fieldname "&gt;
&lt;!ATTLIST methodname     class CDATA "+ topic/keyword pr-d/apiname cl-d/methodname "&gt;
</pre>

          </li>

        </ol>

        <p>The complete element definition file would look as follows:</p>

        <pre class="codeblock">&lt;!ENTITY % classname  "classname"&gt;
&lt;!ENTITY % fieldname  "fieldname"&gt;
&lt;!ENTITY % methodname "methodname"&gt;

&lt;!ELEMENT classname        (#PCDATA)&gt;
&lt;!ELEMENT fieldname        (#PCDATA)&gt;
&lt;!ELEMENT methodname       (#PCDATA)&gt;

&lt;!ATTLIST classname      class CDATA "+ topic/keyword pr-d/apiname cl-d/classname "&gt;
&lt;!ATTLIST fieldname      class CDATA "+ topic/keyword pr-d/apiname cl-d/fieldname "&gt;
&lt;!ATTLIST methodname     class CDATA "+ topic/keyword pr-d/apiname cl-d/methodname "&gt;
</pre>

      </div>

      <div class="section"><h3 class="sectiontitle">Writing the shell DTD</h3>
        
        <p>After creating the domain files, you can write shell DTDs to combine the domain with topics and other domains. The shell DTD must include all domain dependencies. </p>

        <p>In the scenario, the shell DTD combines the class library domain with the concept, reference, and task topics and the programming domain. The portions specific to the class library domain are highlighted below in bold:</p>

        <pre class="codeblock">&lt;!--vocabulary declarations--&gt;
&lt;!ENTITY % pr-d-dec PUBLIC "-//IBM//ENTITIES DITA Programming Domain//EN" "programming-domain.ent"&gt;
  %pr-d-dec;
<strong>&lt;!ENTITY % cl-d-dec SYSTEM "classlib-domain.ent"&gt; %cl-d-dec;</strong>

&lt;!--vocabulary substitution--&gt;
&lt;!ENTITY % pre     "pre     | %pr-d-pre;"&gt;
&lt;!ENTITY % keyword "keyword | %pr-d-keyword; <strong>| %cl-d-apiname;</strong>"&gt;
&lt;!ENTITY % ph      "ph      | %pr-d-ph;"&gt;
&lt;!ENTITY % fig     "fig     | %pr-d-fig;"&gt;
&lt;!ENTITY % dl      "dl      | %pr-d-dl;"&gt;
<strong>&lt;!ENTITY % apiname "apiname | %cl-d-apiname;"&gt;</strong>

&lt;!--vocabulary attributes--&gt;
&lt;!ATTLIST concept    domains CDATA "&amp;pr-d-att; <strong>&amp;cl-d-att;</strong>"&gt;
&lt;!ATTLIST reference  domains CDATA "&amp;pr-d-att; <strong>&amp;cl-d-att;</strong>"&gt;
&lt;!ATTLIST task       domains CDATA "&amp;pr-d-att; <strong>&amp;cl-d-att;</strong>"&gt;

&lt;!--Redefine the infotype entity to exclude other topic types--&gt;
&lt;!ENTITY % info-types "concept | reference | task"&gt;

&lt;!--Embed topic to get generic elements --&gt;
&lt;!ENTITY % topic-type PUBLIC "-//IBM//ELEMENTS DITA Topic//EN" "topic.mod"&gt;
  %topic-type;

&lt;!--Embed topic types to get specific topic structures--&gt;
&lt;!ENTITY % concept-typemod PUBLIC "-//IBM//ELEMENTS DITA Concept//EN" "concept.mod"&gt;
  %concept-typemod;
&lt;!ENTITY % reference-typemod PUBLIC "-//IBM//ELEMENTS DITA Reference//EN" "reference.mod"&gt;
  %reference-typemod;
&lt;!ENTITY % task-typemod PUBLIC "-//IBM//ELEMENTS DITA Task//EN" "task.mod"&gt;
  %task-typemod;

&lt;!--vocabulary definitions--&gt;
&lt;!ENTITY % pr-d-def PUBLIC "-//IBM//ELEMENTS DITA Programming Domain//EN" "programming-domain.mod"&gt;
  %pr-d-def;
<strong>&lt;!ENTITY % cl-d-def SYSTEM "classlib-domain.mod"&gt; %cl-d-def;</strong>
</pre>

        <p>Notice that the class library phrases are added to the element entity for <span class="apiname">keyword</span> as well as for <span class="apiname">apiname</span>. This addition makes the class library phrases available within topic structures that allow keywords and not just in topic structures that explicitly allow API names. In fact, the structures of the <span class="apiname">reference</span> topic specify only keywords, but it's good practice to add the domain specialization entities to all ancestor elements.</p>

      </div>

    </div>

  </div>

  <div class="nested1" id="consideration"><a name="consideration"><!-- --></a>
    <h2 class="topictitle2">Considerations for domain specialization</h2>

    <div>
      <p>When you define new types of topics or domain elements, remember that the hierarchies for topic specialization and domain specialization must be distinct. A specialized topic cannot use a domain element in a content model. Similarly, a domain element can specialize only from an element in the base topic or in another domain. That is, a topic and domain cannot have dependencies. To combine topics and domains, use a shell DTD.</p>

      <p>When specializing elements with internal structure including the <span class="apiname">ul</span>, <span class="apiname">ol</span>, and <span class="apiname">dl</span> lists as well as <span class="apiname">table</span> and <span class="apiname">simpletable</span>, you should specialize the entire content element. Creating special types of pieces of the internal structure independently of the whole content structure usually doesn't make much sense. For example, you usually want to create a special type of list instead of a special type of <span class="apiname">li</span> list item for ordinary <span class="apiname">ul</span> and <span class="apiname">ol</span> lists.</p>

      <p>You should never specialize from the elements of the highlight domain. These style elements do not have a specific semantic. Although the formatting of the highlight styles might seem convenient, you might find you need to change the formatting later. </p>

      <p>As noted previously, you should use element entities instead of literal element names in content models. The element entities are necessary to permit domain specialization. </p>

      <p>The content model should allow for the possibility that the element entity might expand to a list. When applying a modifier to the element entity, you should enclose the element entity in parentheses. Otherwise, the modifier will apply only to the last element if the entity expands to a list. Similar issues affect an element entity in a sequence:</p>

      <pre class="codeblock">..., ( %classname; ), ...
... ( %classname; )? ...

... ( %classname; )* ...
... ( %classname; )+ ...
... | %classname; | ...
</pre>

      <p>The parentheses aren't needed if the element entity is already in a list.</p>

    </div>

  </div>

  <div class="nested1" id="generalize"><a name="generalize"><!-- --></a>
    <h2 class="topictitle2">Generalizing a domain</h2>

    <div>
      <p>As with topics, a specialized content element can be generalized to one of its ancestor elements. In the previous scenario, a <span class="apiname">classname</span> can generalize to <span class="apiname">apiname</span> or even <span class="apiname">keyword</span>. As a result, documents using different domains but the same topics can be exchanged or merged without having to generalize the topics.</p>

      <p>To return to the highlight style controversy mentioned in <a href="#base">Understanding the base domains</a>, a pragmatic document authored with highlight domain will contain phrases like the following:</p>

      <pre class="codeblock">... the &lt;b&gt;important&lt;/b&gt; point is ...</pre>

      <p>When the document is generalized to the same topic but without the highlight domain, the pragmatic <span class="apiname">b</span> element becomes a purist <span class="apiname">ph</span> element, indicating that the phrase is special without introducing presentation:</p>

      <pre class="codeblock">... the &lt;ph class="+ topic/ph hi-d/b "&gt;important&lt;/ph&gt; point is ...</pre>

      <p>In the previous scenario, the class library authors could send their topics to another DITA shop without the class library domain. The recipients would generalize the class library topics, converting the <span class="apiname">classname</span> elements to <span class="apiname">apiname</span> base elements. After generalization, the recipients could edit and process the class, field, and method names in the same way as any other API names. That is, the situation would be the same as if the senders had decided not to distinguish class, field, and method names and, instead, had marked up these names as generic API names.</p>

      <p>As an alternative, the recipients could decide to add the class library domain to their definitions. In this approach, the senders would provide not only their topics but also the entity declaration and element definition files for the domain. The recipients would add the class library domain to their shell DTD. The recipients could then work with <span class="apiname">classname</span> elements without having to generalize.</p>

      <p>The recipients can use additional domains with no impact on interoperability. That is, the shell DTD for the recipients could use more domains than the shell DTD for the senders without creating any need to modify the topics. </p>

      <div class="note"><span class="notetitle">Note:</span> When defining specializations, you should avoid introducing a dependency on special processing that lacks a graceful fallback to the processing for the base element. In the scenario, special processing for the <span class="apiname">classname</span> element might generate a literal <span class="q">"class"</span> label in the output to save some typing and produce consistent labels. After automated generalization, however, the label would not be supplied by the base processing for the <span class="apiname">apiname</span> element. Thus, the dependency would require a special generalization transform to append the literal <span class="q">"class"</span> label to <span class="apiname">classname</span> elements in the source file.</div>

    </div>

  </div>

  <div class="nested1" id="summary"><a name="summary"><!-- --></a>
    <h2 class="topictitle2">Summary</h2>

    <div>
      <p>Through topic specialization and domains, DITA provides the following benefits:</p>

      <ul>
        <li>
          <p>Simpler topic design.</p>

          <p>The document designer can focus on the structure of the topic without having to foresee every variety of content used within the structure.</p>

        </li>

        <li>
          <p>Simpler topic hierarchies.</p>

          <p>The document designer can add new types of content without having to add new types of topics.</p>

        </li>

        <li>
          <p>Extensible content for existing topics.</p>

          <p>The document designer can reuse existing types of topics with new types of content. </p>

        </li>

        <li>
          <p>Semantic precision.</p>

          <p>Content elements with more specific semantics can be derived from existing elements and used freely within documents. </p>

        </li>

        <li>
          <p>Simpler element lists for authors.</p>

          <p>The document designer can select domains to minimize the element set. Authors can learn the elements that are appropriate for the document instead of learning to disregard unneeded elements. </p>

        </li>

      </ul>

      <p> In short, the DITA domain feature provides for great flexibility in extending and reusing information types. The highlight, programming, and UI domains provided with the base DITA release are only the beginning of what can be accomplished.</p>

      <div class="section"><h3 class="sectiontitle">Notices</h3>
        
        <blockquote>
          <p>© Copyright International Business Machines Corp., 2002, 2003. All rights reserved.</p>

          <p>The information provided in this document has not been submitted to any formal IBM test and is distributed "AS IS," without warranty of any kind, either express or implied. The use of this information or the implementation of any of these techniques described in this document is the reader's responsibility and depends on the reader's ability to evaluate and integrate them into their operating environment. Readers attempting to adapt these techniques to their own environments do so at their own risk. </p>

        </blockquote>

      </div>

    </div>

  </div>


</body>
</html>